home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / applications / misc / cross50.lha / cross / doc / CrossE.doc < prev    next >
Encoding:
Text File  |  1993-05-20  |  16.0 KB  |  427 lines
  1. Cross V5.0
  2. ==========
  3. Documentation
  4. =============
  5.  
  6. Cross V5.0 is a computer aided crossword construction program (I guess
  7. `CACC' might be a nice acronym for that :-). It should work with any
  8. Amiga configuration if you're using at least Kickstart 2.04 (37.175).
  9. Cross should work with all memory configurations, including 512 KB.
  10. However I recommend 1 MB of RAM or more.
  11.  
  12. Currently Cross V5.0 supports four different languages: English, German,
  13. Italian and Esperanto. New translations can be added easily, because
  14. almost all the messages are collected in a single ASCII text file.
  15. I'm currently looking for additional translations.
  16.  
  17. Cross V5.0 is Freeware. You may copy it freely as long as you are not
  18. making profits that way.
  19.  
  20. Cross V5.0 is completely font sensitive and adapts to both the resoultion
  21. and color palette of your Workbench screen.
  22.  
  23. Some legalese
  24. =============
  25. Copyright
  26. ---------
  27. Program and documentation are (C) Copyright 1991,92,93 by
  28.  
  29.   Jürgen Weinelt
  30.   Zur Kanzel 1
  31.   D-8783 Hammelburg
  32.   Germany
  33.  
  34. Non-profit distribution is permitted. Any other distribution is a violation
  35. of my copyright and will be prosecuted.
  36.  
  37. Disclaimer
  38. ----------
  39. Cross was carefully tested on several different Amiga configurations and
  40. I'm currently not aware of any major bugs. You are however using this
  41. software at your own risk; that is, if it breaks something, it's your
  42. problem and NOT mine. I think this is a fair deal, because you
  43. received this software for free.
  44.  
  45. Bug reports
  46. -----------
  47. If you find any bugs in this program, please contact me immediately. I will
  48. try to fix problems as soon as possible. You can find my address in the
  49. copyright notice above. If you have EMail access, you can also reach me as
  50.  
  51.    jow@sun.rz.uni-wuerzburg.de (preferred)
  52.    jow@hcast.adsp.sub.org
  53.    jow@hcast.franken.de
  54.  
  55. I'm the proud owner of several different Amigas, including a brand new
  56. A4000/040. I'm testing my programs with the latest OS beta versions and
  57. I'm trying to avoid compatibility risks wherever I can. If you contact
  58. me with a bug report, please be sure to include a detailed description
  59. of your hardware and software configuration, as well as a detailed description
  60. of `your' bug.
  61.  
  62. Special rules for international mail
  63. ------------------------------------
  64. German users are required to send me return postage; unfortunately this
  65. is almost impossible from outside Germany, because I can't use foreign
  66. stamps, and trying to exchange small amounts of money at a bank is
  67. quite expensive. Therefore I ask you to include a picture postcard
  68. or a photograph of your home town with your first letter as a
  69. substitute for the return postage. This is NOT a shareware fee or such.
  70.  
  71. Program documentation
  72. =====================
  73. Starting Cross
  74. --------------
  75. There are two possible command lines for starting Cross from the shell:
  76.  
  77.   Cross
  78.  
  79. This is the usual way of starting cross. Use it whenever you just want to
  80. work with the program normally.
  81.  
  82.   Cross -d
  83.  
  84. If you start Cross with this command line, you enter a special message data
  85. debug mode; messages will be displayed together with the corresponding message
  86. number. This is only needed if you've created a new translation and you want
  87. to debug obscure problems with it. More documentation on this will follow later.
  88.  
  89. You need to add a `ASSIGN Cross: somewhere' before starting the program,
  90. where `somewhere' is the place where you installed the Cross main
  91. directory. Cross needs this to find its additional files:
  92.  
  93.   File or directory     | Meaning
  94.   ======================#===================================
  95.   DATA                  | data directory
  96.   ----------------------+-----------------------------------
  97.   DATA/Cross.prefs      | contains user preferences
  98.   ----------------------+-----------------------------------
  99.   DATA/msgtxt.data      | contains the mulitlingual messages
  100.   ----------------------+-----------------------------------
  101.   DATA/words_eng.crw    | German word data file
  102.   DATA/words_ger.crw    | English word data file
  103.   DATA/words_ita.crw    | Italian word data file
  104.   DATA/words_eto.crw    | Esperanto word data file
  105.   ----------------------+-----------------------------------
  106.   DATA/ (...) .crd      | crossword data files
  107.   ----------------------+-----------------------------------
  108.  
  109. The menus
  110. ---------
  111. Most of the menus are self-explanatory. Here's a short description
  112. of their meaning:
  113.  
  114. The Project menu
  115. ----------------
  116. This is where you find all the input and output operations.
  117.  
  118. Project: New crossword
  119. ----------------------
  120. After a safety check the old crossword puzzle is discarded and a
  121. new (blank) one is prepared.
  122.  
  123. Project: Load crossword
  124. -----------------------
  125. A crossword data file will be read from disk.
  126.  
  127. The suggested file name extension for crossword data files is `.crd'.
  128.  
  129. The crossword that you're currently editing will be discarded
  130. without an additional warning.
  131.  
  132. Project: Load word data file
  133. ----------------------------
  134. A different word data file will be loaded.
  135.  
  136. The suggested file name extension for word data files is `.crw'.
  137.  
  138. Project: save crossword
  139. -----------------------
  140. The crossword that you're currently working on will be saved.
  141.  
  142. The suggested file name extension for crossword data files is `.crd'.
  143.  
  144. Project: Save settings
  145. ----------------------
  146. The current language and the current crossword size will be saved to
  147. `Cross:data/Cross.prefs'. Cross reads this file during its startup
  148. and initializes according to what it finds there.
  149.  
  150. Project: Printer
  151. ----------------
  152. All the printer functions are located in this submenu.
  153.  
  154. Projekt: Printer: Print crossword (plain)
  155. -----------------------------------------
  156. I seriously hope you will never have to resort to this function; it does work
  157. on almost any printer except for some really very exotic models, but what you
  158. get is definitely not what one might call `nice' or `good looking'.
  159.  
  160. Project: Printer: Print crossword (LaTeX)
  161. -----------------------------------------
  162. If you're a LaTeX user, you can use this function to write the current crossword
  163. as a LaTeX source file. You may have to experiment with the paper width and
  164. paper height settings of your LaTeX environment. Try changing
  165. "\oddsidemargin", "\textwidth", "\hoffset" and "\voffset".
  166. Change the "\unitlength" to resize the crossword globally.
  167.  
  168. Project: Printer: Print crossword (pretty)
  169. ------------------------------------------
  170. This is the first choice for printing crosswords; it should work with every
  171. graphics printer, if the printer was configured correctly through the printer
  172. preferences. This mode requires relatively much RAM, there may be problems
  173. with 512 KB Amigas.
  174.  
  175. Project: Printer: Print crossword (pretty/numbers)
  176. --------------------------------------------------
  177. This function is identical to the previous one, but it will also insert a
  178. clue number into the crossword grid wherever a word starts. If you create
  179. a clue list (you'll have to do this manually, there's no support for that in
  180. Cross), you get another popular type of crossword.
  181.  
  182. You will probably need a printer resolution of 300 DPI or better for this
  183. feature. At lower resolutions the clue numbers may look ugly.
  184.  
  185. Project: Printer: Print crossword solution
  186. ------------------------------------------
  187. Since there are no graphics to be printed here, this function is the same for
  188. every printer.
  189.  
  190. Project: About
  191. --------------
  192. Cross displays a requester with its version number and copyright notice.
  193. You can also find my postal and EMail address there.
  194.  
  195. Project: Quit
  196. -------------
  197. After a safety requester the program ends.
  198.  
  199. The Edit menu
  200. -------------
  201. Here you'll find all the editing functions you need to create crosswords.
  202.  
  203. Edit: Auto search mode
  204. ----------------------
  205. While the auto search mode is active, Cross tries to find words that
  206. fit into the crossword. Two conditions must be met:
  207.  
  208.   1. a word data file must be present (that is, in memory)
  209.  
  210.   2. at least one word must have been placed as a ``seed word'' from
  211.      which the rest of the crossword can grow.
  212.  
  213. While the auto search is running, a progress requester with two progress bars
  214. is displayed. The first bar corresponds to the `limit' variable, the second
  215. one shows the progress of the current search attempt. The auto search mode is
  216. finished by clicking on the `Stop' gadget, or when no more words can be placed.
  217.  
  218. Edit: Place word manually
  219. -------------------------
  220. Enter the word into the string requester and press return (or click on the
  221. `Confirm' gadget). Then select a grid position by placing your mouse pointer
  222. over the desired position and clicking the left mouse button. A second requester may
  223. appear if it's  not clear whether to place the word horizontally or vertically.
  224.  
  225. Edit: Remove word manually
  226. --------------------------
  227. Select the word to be removed by moving the mouse pointer over any of its
  228. letters and then clicking the left mouse button. A second requester may then appear
  229. if it's not clear which word to remove.
  230.  
  231. If you have selected this function by accident, you may cancel it by pointing at
  232. an empty grid position and then clicking the left mouse button.
  233.  
  234. This menu item is selectable only when at least one word has been placed.
  235.  
  236. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  237. Please be careful when using this function because there are some
  238. nasty problems involved with it. Look at the following example:
  239.  
  240.      E
  241.      V
  242.      E
  243.      N
  244.    OUTDOOR
  245.       U
  246.       B
  247.  
  248. If you delete the word OUTDOOR, you get the following situation:
  249.  
  250.        E
  251.        V
  252.        E
  253.        N
  254.        TD
  255.         U
  256.         B
  257.  
  258. If you look closely now, you will notice that there's suddenly a new word
  259. `TD' that has not been placed explicitly. Nasty, isn't it?
  260. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  261.  
  262. Edit: Reset length limit
  263. ------------------------
  264. Cross uses the limit variable to make sure that long words are placed
  265. before Cross resorts to short words. Words must have at least the length
  266. stated by `limit' or they will not be placed. `limit' is decremented
  267. automagically when no more words can be placed. Use this function to
  268. reset `limit' to any even value between 0 and 18.
  269.  
  270. Edit: Set crossword size
  271. ------------------------
  272. A requester asks for the width and height of your crossword. Please note
  273. that width and height must be odd numbers. This function is only available
  274. when no words have been placed.
  275.  
  276. Edit: Put seed words
  277. --------------------
  278. Use this function to place the four seed words from which the rest of
  279. your crossword will grow. You might also decide to place those seeds
  280. manually instead, in this case use `Edit: Place words manually'.
  281.  
  282. This function is not available if words have already been placed.
  283.  
  284. The Language menu
  285. -----------------
  286. For each language there is one menu item in this menu. Currently you
  287. can choose from English, German, Italian and Esperanto.
  288. Whenever you select a language from this menu, Cross reloads the
  289. corresponding message texts and redraws its screen.
  290.  
  291. You can make a language selection permanent by selecting
  292. `Project: Save settings'. It will be then loaded as default whenever you
  293. start Cross.
  294.  
  295.  
  296.  
  297. File documentation
  298. ==================
  299. The message data file
  300. ---------------------
  301. This file contains virtually every text used by Cross, at the moment there
  302. are messages in English, German, Italian and Esperanto. Other languages can be
  303. added easily (up to 9 languages).
  304.  
  305. Each entry in the message data file uses exactly one line.
  306.  
  307. Structure of the message data file
  308. ----------------------------------
  309. The first line of the message data file contains one single digit; this is
  310. the number of languages currently available. This is followed by the name of
  311. each language (currently ENGLISH, DEUTSCH, ITALIAN and ESPERANTO).
  312.  
  313. ########################################################################
  314. Have you added another language to the message data file?
  315. Please send me a copy of your message data file on disk, I will
  316. include it with the next release of Cross.
  317. ########################################################################
  318.  
  319. The following entries are present once for each language, too. These are the
  320. program messages.
  321.  
  322. Additional informations
  323. -----------------------
  324. If you want to add another language to the message data file, please make
  325. sure that your translation has approximately the same size as the original
  326. message, because some of them appear in requesters, menus or gadgets.
  327.  
  328. Each message must start with a three digit number. This number must be
  329. itentical to the actual number of the message (actual maeans, what you'd
  330. get by counting them). Just take a look at the message data file, this is
  331. easier than it sounds.
  332.  
  333. The only exception to this rule is the message number `999' which signals
  334. the `end of file'.
  335.  
  336. Debug mode
  337. ----------
  338. If you encounter any problems after adding another language, just start
  339. Cross with the message debug mode active (add parameter `-d' from
  340. the shell). This causes the message numbers to be displayed along with the
  341. messages. It will hopefully help you locate the problem.
  342.  
  343. Word data files
  344. ---------------
  345. If you want to create your own word data files, please note:
  346.  
  347.   1. You may use every character you want to, including even national characters,
  348.      blanks, dashes, etc. It's up to you to make sure that the words
  349.      actually make sense
  350.  
  351.   2. The word length should always be odd,that is, 3,5,7, ..., 25 (except for
  352.      two letter words). This limitation is needed to improved the structure
  353.      of the crossword. You're alolowed to use words with even length, but this
  354.      will probably cause larger gaps in the crossword grid.
  355.  
  356.   3. Word length must be at least 2 characters, and no more than 25 characters.
  357.  
  358.   4. The word data file must not contain empty lines.
  359.  
  360.   5. The last entry may or may not be `***END***', without the quotation
  361.      marks, of course.  The ``***END***'' is not needed, but will be
  362.      ignored if present.
  363.  
  364. The PreProcessor
  365. ----------------
  366. Yes, you're right. There is an easier way of creating word data files...
  367. Just run any standard ASCII text file through the "PreProcessor", which
  368. should also be somewhere in the "Cross" drawer. PreProcessor will break it
  369. down into single words and will remove anything illegal (PreProcessor still
  370. uses the strict Version 3 rules for words). You'll have to use
  371. your favourite editor though to delete all those words you don't want to use.
  372. There may also be some "crippled" words that didn't survive the PreProcessor.
  373.  
  374. Usage of the PreProcessor
  375. -------------------------
  376. There are no command line parameters; file selection is done with file
  377. requesters.
  378.  
  379. Additional note
  380. ---------------
  381. The PreProcessor uses a recursive algorithm (builds a binary tree
  382. to sort the words); please make sure there's enough stack space
  383. available. You can increase the stack space with a CLI command
  384. called "STACK". PreProcessor automatically allocates 50000 bytes
  385. of stack space; if you need more than that, use the STACK command.
  386. PreProcessor is very greedy anyway... there may be problems
  387. with it on 512K Amigas if you try to convert large ASCII
  388. text files.
  389.  
  390. Large word data files
  391. ---------------------
  392. Just a warning: if your word data file is very large, the creation of the
  393. crossword will be slowed down considerably. In order to avoid this effect,
  394. you might use several small word data files, loading the next when the
  395. current file is used up.
  396.  
  397.   File              | Word length
  398.   ------------------+------------
  399.   words_ger05.crw   | 25-17
  400.   words_ger06.crw   | 15-9
  401.   words_ger07.crw   |  7-5
  402.   words_ger08.crw   |  3-2
  403.  
  404.  
  405.  
  406. Miscellaneous
  407. =============
  408. Known problems/bugs of Cross
  409. ----------------------------
  410. Using a very large font (about 25-30 points ore more) may cause error messages
  411. or even fatal errors. I know how to fix this, but it is a major change and would
  412. take quite some time to fix. I will eventually do it, but it was too much work
  413. for this release. As a workaround, select a smaller font size from the
  414. Workbench font preferences.
  415.  
  416. I know of no other bugs at the moment.
  417.  
  418. If you encounter any bugs, please send me a detailed description of the bug and
  419. your hard- and software configuration.
  420.  
  421. Future improvements and plans
  422. -----------------------------
  423.   1. several patterns for setting the ``seed words''
  424.   2. crosswords with custom layouts instead of rectangles
  425.   3. AREXX port
  426.   4. Support for the new Workbench 2.1 locale routines
  427.